Form Actions

 started in 2005, jstaniek
 macros support added in 2006, dipesh
 updated in december 2006 for Kexi 1.1.2, jstaniek

<< Back to Forms

Table of Contents    Action Categories      Usage of the action categories    The action selection dialog    Actions assignments at runtime    Storage format for action assignments

At the moment it's possible to connect a button with "Assign Action" with a shared action Kexi provides to execute a predefined (global i.e. shared or local) action if the button has been clicked.

Action Categories

It's not that productive to just execute a global action -- sometimes there's a need for executing action in a context of a given object. So there are more ways available to execute actions. These ways are the reason for existence of so called action categories. The following categories are identified and implemented:

• No Category - the action will not be visible at all
• Global Category - for global actions like "edit_copy", available in the main menu and context menus; can be also applied to focused widget (of many types)
• Part Item Category - action related to a part item (e.g. a context menu's action within the project navigator); example: "data_execute" which executes a macro or script; actions of this category require context, used only in the navidator
• Window Category - action related to active window, which can display a table, query, form, report; actions like "move to next row" belong to this category; currently only forms are be supported; while this category is being declared for an action, it must be specified what types of objects are supported (eg. KexiPart::TableObjectType, KexiPart::QueryObjectType, KexiPart::FormObjectType); ther can be more than one type supported by the same action

These categories can be combined, e.g. "edit_delete" is supported both by Part Item and Global action categories. Actions can be in at least one category called "No category" -- actions without categories will not be visible within the actions selection dialog.

Usage of the action categories

The categories can be defined using Kexi::ActionCategories helper class of kexicore library. There is a singleton object available using Kexi::ActionCategories* Kexi::actionCategories() static function, used by KexiMainWindowImpl::initActions(). All shared actions are and should be declared for zero or more categories.

The reason for configuring action categories at the top level (main window) is that we need this to be performed once and have it related to shared actions (whose are declared at KexiMainWindowImpl object's level).

The action selection dialog

The dialog allows to select a single action that will be assigned to a previously selected button widget. The only way for now to show the dialog is to select the 'Assign Action...' command from the button's context menu in the form's Design View.

The dialog is implemented by KexiActionSelectionDialog class of kexiformutils library.

Actions assignments at runtime

KexiFormEventHandler class takes care of initializing physical (signal-slot) assignments for predefined design-time assignments stored in a form design. KexiFormEventAction class takes care of decoding the storege format (e.g. "table:cars") into a set of well defined data members and provides activation routine (KexiFormEventAction::activate()) for actions that require a context to be executed. Global actions are executed automatically as a response to previously performed signal-slot connection between button's clicked() signal and shared (global) action's activate() slot (see KexiFormEventHandler::setMainWidgetForEventHandling()).

Storage format for action assignments

Kexi Form's XML file format (which is in turn Qt Designer-based) has been utilized to store action assignment information. The extenstion is an effect of using two additional Qt properties of the button widget class:

• onClickAction
• onClickActionOption

This gives the following XML chunk:

 <widget class="KexiPushButton" >
   ...
   <property name="onClickAction" >
      <string>{actionCategoryAndName}</string>
   </property>
   <property name="onClickActionOption" >
      <string>{actionOption}</string>
   </property>
   ....
 </widget>

where {actionCategoryAndName} and {actionOption} denote action name and optional category. There are following cases:

• kaction:{actionName} - a global action with name {actionName} specified without parameters; example: kaction:data_cancel_row_changes. This case corresponds with actions from 'Global Category' as described above. {actionOption} property should be empty for this case.
• currentForm:{actionName} - a local action related to the current form. This case corresponds with actions from 'Window Category' as described above. {actionOption} property should be empty for this case.
• {objectType}:{objectName} - an action executed in context of an object pointed by name and type (as for instance there can be table and field with the same name). Example type/name pair stored as the onClickAction property value is table:cars. The {objectType} is in fact a part of Kexi object's mime types, e.g. 'table' for 'kexi/table' mime type. This case corresponds with actions from 'Part Item Category' as described above. {actionOption} property provides action name to be executed for the specified object. Possible actions names are in this case:
  • open - opens the object in data view (macros and scripts will be opened in design view if possible)
  • execute - executes the object (only available for macros and scripts)
  • print - shows the system print dialog for simple printout of the object (actually only table or query)
  • printPreview - like for print but shows the "Print preview" window
  • pageSetup - like for print but shows the "Print Setup" window
  • exportToCSV - shows the "Export To CSV" dialog that provides options for exporting data from the pointed table or query to a CSV file (actually only available for tables and queries)
  • copyToClipboardAsCSV - like for exportToCSV but shows the "Copy To CSV" dialog
  • new - creates a window for new object of given type, without saving it (objectName is ignored)
  • design - opens the object in design view
  • editText - opens the object in text view (actually available only for queries)
  • close - closes window with the object if it's opened

Thanks to using properties and prefixes, the assignment format is open for future extensions (e.g. for adding new actions or contexts and object types).

For backward compatibility with Kexi < 1.1.2, where there were no action options available: if there is no {actionOption} property provided, open is assumed for all object types except macros and scripts, for whose execute action is assumed.